<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>HTTP</title>
<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../index.html" title="Chapter 1. Boost.Beast">
<link rel="up" href="../index.html" title="Chapter 1. Boost.Beast">
<link rel="prev" href="config/configuration_preprocessor_defin.html" title="Configuration Preprocessor Definitions">
<link rel="next" href="using_http/protocol_primer.html" title="Protocol Primer">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
<td align="center"><a href="../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="config/configuration_preprocessor_defin.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="using_http/protocol_primer.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="beast.using_http"></a><a class="link" href="using_http.html" title="HTTP">HTTP</a>
</h2></div></div></div>
<div class="warning"><table border="0" summary="Warning">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../../../doc/src/images/warning.png"></td>
<th align="left">Warning</th>
</tr>
<tr><td align="left" valign="top"><p>
        Higher level functions such as Basic Authentication, mime/multipart encoding,
        cookies, automatic handling of redirects, gzipped transfer encodings, caching,
        or proxying (to name a few) are not directly provided, but nothing stops
        users from creating these features using Beast's HTTP message types.
      </p></td></tr>
</table></div>
<p>
      This library offers programmers simple and performant models of HTTP messages
      and their associated operations including synchronous, asynchronous, and buffer-oriented
      parsing and serialization of messages in the HTTP/1 wire format using <a href="../../../../../libs/asio/index.html" target="_top">Boost.Asio</a>. Specifically, the library
      provides:
    </p>
<div class="variablelist">
<p class="title"><b></b></p>
<dl class="variablelist">
<dt><span class="term">Message Containers</span></dt>
<dd><p>
            Complete HTTP messages are modeled using the <a class="link" href="ref/boost__beast__http__message.html" title="http::message"><code class="computeroutput"><span class="identifier">message</span></code></a> class, with possible
            user customizations.
          </p></dd>
<dt><span class="term">Stream Reading</span></dt>
<dd><p>
            The functions <a class="link" href="ref/boost__beast__http__read.html" title="http::read"><code class="computeroutput"><span class="identifier">read</span></code></a>, <a class="link" href="ref/boost__beast__http__read_header.html" title="http::read_header"><code class="computeroutput"><span class="identifier">read_header</span></code></a>, <a class="link" href="ref/boost__beast__http__read_some.html" title="http::read_some"><code class="computeroutput"><span class="identifier">read_some</span></code></a>, <a class="link" href="ref/boost__beast__http__async_read.html" title="http::async_read"><code class="computeroutput"><span class="identifier">async_read</span></code></a>, <a class="link" href="ref/boost__beast__http__async_read_header.html" title="http::async_read_header"><code class="computeroutput"><span class="identifier">async_read_header</span></code></a>, and <a class="link" href="ref/boost__beast__http__async_read_some.html" title="http::async_read_some"><code class="computeroutput"><span class="identifier">async_read_some</span></code></a> read HTTP/1
            message data from a <a class="link" href="concepts/streams.html" title="Streams">stream</a>.
          </p></dd>
<dt><span class="term">Stream Writing</span></dt>
<dd><p>
            The functions <a class="link" href="ref/boost__beast__http__write.html" title="http::write"><code class="computeroutput"><span class="identifier">write</span></code></a>, <a class="link" href="ref/boost__beast__http__write_header.html" title="http::write_header"><code class="computeroutput"><span class="identifier">write_header</span></code></a>, <a class="link" href="ref/boost__beast__http__write_some.html" title="http::write_some"><code class="computeroutput"><span class="identifier">write_some</span></code></a>, <a class="link" href="ref/boost__beast__http__async_write.html" title="http::async_write"><code class="computeroutput"><span class="identifier">async_write</span></code></a>, <a class="link" href="ref/boost__beast__http__async_write_header.html" title="http::async_write_header"><code class="computeroutput"><span class="identifier">async_write_header</span></code></a>, and <a class="link" href="ref/boost__beast__http__async_write_some.html" title="http::async_write_some"><code class="computeroutput"><span class="identifier">async_write_some</span></code></a> write HTTP/1
            message data to a <a class="link" href="concepts/streams.html" title="Streams">stream</a>.
          </p></dd>
<dt><span class="term">Serialization</span></dt>
<dd><p>
            The <a class="link" href="ref/boost__beast__http__serializer.html" title="http::serializer"><code class="computeroutput"><span class="identifier">serializer</span></code></a> produces a series
            of octet buffers conforming to the <a href="https://tools.ietf.org/html/rfc7230" target="_top">rfc7230</a>
            wire representation of a <a class="link" href="ref/boost__beast__http__message.html" title="http::message"><code class="computeroutput"><span class="identifier">message</span></code></a>.
          </p></dd>
<dt><span class="term">Parsing</span></dt>
<dd><p>
            The <a class="link" href="ref/boost__beast__http__parser.html" title="http::parser"><code class="computeroutput"><span class="identifier">parser</span></code></a> attempts to convert a
            series of octet buffers into a <a class="link" href="ref/boost__beast__http__message.html" title="http::message"><code class="computeroutput"><span class="identifier">message</span></code></a>.
          </p></dd>
</dl>
</div>
<p>
      Interfaces for operating on HTTP messages are structured into several layers.
      The highest level provides ease of use, while lower levels provide progressively
      more control, options, and flexibility. At the lowest level customization points
      are provided, where user defined types can replace parts of the implementation.
      The layers are arranged thusly:
    </p>
<div class="informaltable"><table class="table">
<colgroup>
<col>
<col>
<col>
</colgroup>
<thead><tr>
<th>
              <p>
                Level
              </p>
            </th>
<th>
              <p>
                Read/Write What
              </p>
            </th>
<th>
              <p>
                Description
              </p>
            </th>
</tr></thead>
<tbody>
<tr>
<td>
              <p>
                <span class="bold"><strong>6</strong></span>
              </p>
            </td>
<td>
              <p>
                <a class="link" href="ref/boost__beast__http__message.html" title="http::message"><code class="computeroutput"><span class="identifier">message</span></code></a>
              </p>
            </td>
<td>
              <p>
                At the highest level, these free functions send or receive a complete
                HTTP message in one call. They are designed for ease of use: <a class="link" href="ref/boost__beast__http__read/overload4.html" title="http::read (4 of 4 overloads)"><code class="computeroutput"><span class="identifier">read</span></code></a>, <a class="link" href="ref/boost__beast__http__write/overload4.html" title="http::write (4 of 6 overloads)"><code class="computeroutput"><span class="identifier">write</span></code></a>, <a class="link" href="ref/boost__beast__http__async_read/overload2.html" title="http::async_read (2 of 2 overloads)"><code class="computeroutput"><span class="identifier">async_read</span></code></a>, and <a class="link" href="ref/boost__beast__http__async_write/overload2.html" title="http::async_write (2 of 3 overloads)"><code class="computeroutput"><span class="identifier">async_write</span></code></a>.
              </p>
            </td>
</tr>
<tr>
<td>
              <p>
                <span class="bold"><strong>5</strong></span>
              </p>
            </td>
<td>
              <p>
                <a class="link" href="ref/boost__beast__http__parser.html" title="http::parser"><code class="computeroutput"><span class="identifier">parser</span></code></a>, <a class="link" href="ref/boost__beast__http__serializer.html" title="http::serializer"><code class="computeroutput"><span class="identifier">serializer</span></code></a>
              </p>
            </td>
<td>
              <p>
                For more control, callers may take responsibility for managing the
                required <a class="link" href="ref/boost__beast__http__parser.html" title="http::parser"><code class="computeroutput"><span class="identifier">parser</span></code></a> or <a class="link" href="ref/boost__beast__http__serializer.html" title="http::serializer"><code class="computeroutput"><span class="identifier">serializer</span></code></a> transient state
                objects. This allows additional configuration such as limiting the
                number of bytes for message components during parsing, or regulating
                the size of buffers emitted during output. These functions send or
                receive complete messages using a serializer or parser: <a class="link" href="ref/boost__beast__http__read/overload2.html" title="http::read (2 of 4 overloads)"><code class="computeroutput"><span class="identifier">read</span></code></a>, <a class="link" href="ref/boost__beast__http__write/overload2.html" title="http::write (2 of 6 overloads)"><code class="computeroutput"><span class="identifier">write</span></code></a>, <a class="link" href="ref/boost__beast__http__async_read/overload1.html" title="http::async_read (1 of 2 overloads)"><code class="computeroutput"><span class="identifier">async_read</span></code></a>, and <a class="link" href="ref/boost__beast__http__async_write/overload1.html" title="http::async_write (1 of 3 overloads)"><code class="computeroutput"><span class="identifier">async_write</span></code></a>.
              </p>
            </td>
</tr>
<tr>
<td>
              <p>
                <span class="bold"><strong>4</strong></span>
              </p>
            </td>
<td>
              <p>
                <a class="link" href="ref/boost__beast__http__header.html" title="http::header"><code class="computeroutput"><span class="identifier">header</span></code></a>
              </p>
            </td>
<td>
              <p>
                Sometimes it is necessary to first send or receive the HTTP header.
                For example, to read the header and take action before continuing
                to read the body. These functions use a <a class="link" href="ref/boost__beast__http__parser.html" title="http::parser"><code class="computeroutput"><span class="identifier">parser</span></code></a> or <a class="link" href="ref/boost__beast__http__serializer.html" title="http::serializer"><code class="computeroutput"><span class="identifier">serializer</span></code></a> to read or write
                the header: <a class="link" href="ref/boost__beast__http__read_header/overload2.html" title="http::read_header (2 of 2 overloads)"><code class="computeroutput"><span class="identifier">read_header</span></code></a>, <a class="link" href="ref/boost__beast__http__write_header/overload2.html" title="http::write_header (2 of 2 overloads)"><code class="computeroutput"><span class="identifier">write_header</span></code></a>, <a class="link" href="ref/boost__beast__http__async_read_header.html" title="http::async_read_header"><code class="computeroutput"><span class="identifier">async_read_header</span></code></a>, and
                <a class="link" href="ref/boost__beast__http__async_write_header.html" title="http::async_write_header"><code class="computeroutput"><span class="identifier">async_write_header</span></code></a>.
              </p>
            </td>
</tr>
<tr>
<td>
              <p>
                <span class="bold"><strong>3</strong></span>
              </p>
            </td>
<td>
              <p>
                partial <a class="link" href="ref/boost__beast__http__message.html" title="http::message"><code class="computeroutput"><span class="identifier">message</span></code></a>
              </p>
            </td>
<td>
              <p>
                All of the stream operations at higher levels thus far have operated
                on a complete header or message. At this level it is possible to
                send and receive messages incrementally. This allows resource constrained
                implementations to perform work bounded on storage, or allows better
                control when setting timeouts for example. These functions read or
                write bounded amounts of data and return the number of bytes transacted:
                <a class="link" href="ref/boost__beast__http__read_some/overload2.html" title="http::read_some (2 of 2 overloads)"><code class="computeroutput"><span class="identifier">read_some</span></code></a>, <a class="link" href="ref/boost__beast__http__write_some/overload2.html" title="http::write_some (2 of 2 overloads)"><code class="computeroutput"><span class="identifier">write_some</span></code></a>, <a class="link" href="ref/boost__beast__http__async_read_some.html" title="http::async_read_some"><code class="computeroutput"><span class="identifier">async_read_some</span></code></a>, and <a class="link" href="ref/boost__beast__http__async_write_some.html" title="http::async_write_some"><code class="computeroutput"><span class="identifier">async_write_some</span></code></a>.
              </p>
            </td>
</tr>
<tr>
<td>
              <p>
                <span class="bold"><strong>2</strong></span>
              </p>
            </td>
<td>
              <p>
                <a href="https://tools.ietf.org/html/rfc7230#section-4.1" target="_top"><span class="emphasis"><em>chunked-body</em></span></a>
              </p>
            </td>
<td>
              <p>
                Until now parse and serialize operations apply or remove the chunked
                transfer coding as needed for message payloads whose size is not
                known ahead of time. For some domain specific niches, it is necessary
                to assume direct control over incoming or outgoing chunks in a chunk
                encoded message payload. For parsing this is achieved by setting
                hooks using the functions <a class="link" href="ref/boost__beast__http__parser/on_chunk_header.html" title="http::parser::on_chunk_header"><code class="computeroutput"><span class="identifier">on_chunk_header</span></code></a> and/or
                <a class="link" href="ref/boost__beast__http__parser/on_chunk_body.html" title="http::parser::on_chunk_body"><code class="computeroutput"><span class="identifier">on_chunk_body</span></code></a>. For serializing
                callers may first emit the header, and then use these buffer sequence
                adapters to control the contents of each chunk including <a href="https://tools.ietf.org/html/rfc7230#section-4.1.1" target="_top"><span class="emphasis"><em>chunk
                extensions</em></span></a> and the <a href="https://tools.ietf.org/html/rfc7230#section-4.1.2" target="_top"><span class="emphasis"><em>trailer-part</em></span></a>:
                <a class="link" href="ref/boost__beast__http__chunk_body.html" title="http::chunk_body"><code class="computeroutput"><span class="identifier">chunk_body</span></code></a>, <a class="link" href="ref/boost__beast__http__chunk_crlf.html" title="http::chunk_crlf"><code class="computeroutput"><span class="identifier">chunk_crlf</span></code></a>, <a class="link" href="ref/boost__beast__http__chunk_header.html" title="http::chunk_header"><code class="computeroutput"><span class="identifier">chunk_header</span></code></a>, and <a class="link" href="ref/boost__beast__http__chunk_last.html" title="http::chunk_last"><code class="computeroutput"><span class="identifier">chunk_last</span></code></a>.
              </p>
            </td>
</tr>
<tr>
<td>
              <p>
                <span class="bold"><strong>1</strong></span>
              </p>
            </td>
<td>
              <p>
                buffers
              </p>
            </td>
<td>
              <p>
                For ultimate control, the use of library stream algorithms may be
                bypassed entirely and instead work directly with buffers by calling
                members of <a class="link" href="ref/boost__beast__http__parser.html" title="http::parser"><code class="computeroutput"><span class="identifier">parser</span></code></a> or <a class="link" href="ref/boost__beast__http__serializer.html" title="http::serializer"><code class="computeroutput"><span class="identifier">serializer</span></code></a>.
              </p>
            </td>
</tr>
<tr>
<td>
              <p>
                <span class="bold"><strong>0</strong></span>
              </p>
            </td>
<td>
              <p>
                <span class="emphasis"><em>user-defined</em></span>
              </p>
            </td>
<td>
              <p>
                In addition to the typical customization points of <a class="link" href="concepts/streams.html" title="Streams"><span class="emphasis"><em>Stream</em></span></a>
                and <a class="link" href="concepts/DynamicBuffer.html" title="DynamicBuffer"><span class="emphasis"><em>DynamicBuffer</em></span></a>,
                user-defined types may replace parts of the library implementation
                at the lowest level. The customization points include <a class="link" href="concepts/Fields.html" title="Fields"><span class="emphasis"><em>Fields</em></span></a>
                for creating a container to store HTTP fields, <a class="link" href="concepts/Body.html" title="Body"><span class="emphasis"><em>Body</em></span></a>
                for defining containers and algorithms used for HTTP message payloads,
                and user-defined subclasses of <a class="link" href="ref/boost__beast__http__basic_parser.html" title="http::basic_parser"><code class="computeroutput"><span class="identifier">basic_parser</span></code></a> for implementing
                custom message representation strategies.
              </p>
            </td>
</tr>
</tbody>
</table></div>
<div class="note"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../doc/src/images/note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top">
<p>
        This documentation assumes some familiarity with <a href="../../../../../libs/asio/index.html" target="_top">Boost.Asio</a>
        and the HTTP protocol specification described in <a href="https://tools.ietf.org/html/rfc7230" target="_top">rfc7230</a>.
        Sample code and identifiers mentioned in this section is written as if these
        declarations are in effect:
      </p>
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">beast</span><span class="special">/</span><span class="identifier">http</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">beast</span><span class="special">::</span><span class="identifier">http</span><span class="special">;</span>
</pre>
</td></tr>
</table></div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright © 2016-2019 Vinnie
      Falco<p>
        Distributed under the Boost Software License, Version 1.0. (See accompanying
        file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
      </p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="config/configuration_preprocessor_defin.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="using_http/protocol_primer.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
